OpenAPI Specification
略 : OAS
https://github.com/OAI/OpenAPI-Specification/
よく知られている REST API 記述フォーマット
プログラミング言語に依存しない
OpenAPI Initiative (OAI) が推進している
歴史
以前は Swagger Specification と呼ばれていた
2015 年 11 月に OAI に寄贈され、2016 年に 「OpenAPI Specification」 に改名
Swagger Specification 2.0 が OpenAPI Specification 2.0 に
その後もバージョン更新が行われている ( 参照)
OAS を理解するために OpenAPI Map がおすすめ
記述には次のフォーマットを利用できる
YAML
JSON
文書記述には任意のテキストエディタを使用できる
OAS 対応の Swagger Editor というオンラインエディタがある
Visual Studio Code 用の拡張機能として 『Web API の設計』 では Swagger Viewerと openapi-lint が紹介
OAS を元に API リファレンスマニュアルを生成する方法
Swagger UI や Redoc
コードの自動生成にも利用できる
API ゲートウェイソリューションなども、OAS の API 記述ファイルで設定できる
クエリパラメータ、ボディパラメータ、レスポンスボディを含めて、すべてのデータを JSON Schema で表現
仕様の Shema Object の項目を参照 : https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject (v3.1.0 のリンク)
再利用可能なコンポーネントの定義
components で定義して $ref で参照
スキーマは components の中の schemas で
パラメータは parameters
参考文献
Web API の設計